/**
 *    Copyright 2009-2016 the original author or authors.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */
package org.apache.ibatis.session;

import java.io.Closeable;
import java.sql.Connection;
import java.util.List;
import java.util.Map;

import org.apache.ibatis.cursor.Cursor;
import org.apache.ibatis.executor.BatchResult;


/**
 * Mybatis之中的核心接口,控制整个Mybatis的执行
 */
public interface SqlSession extends Closeable {

  /**
   * 查询单个对象
   * @param statement
   * @return
   */
  <T> T selectOne(String statement);
  
  /**
   * 根据参数查询一个对象
   * @param statement
   * @param parameter
   * @return
   */
  <T> T selectOne(String statement, Object parameter);

  /**
   * 查询一组对象
   * @param statement
   * @return
   */
  <E> List<E> selectList(String statement);

  /**
   * 根据参数查询一组对象
   * @param statement
   * @param parameter
   * @return
   */
  <E> List<E> selectList(String statement, Object parameter);

  /**
   * 带分页的查询一组对象列表
   * @param statement
   * @param parameter
   * @param rowBounds
   * @return
   */
  <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds);

  
  <K, V> Map<K, V> selectMap(String statement, String mapKey);

  /**
   * The selectMap is a special case in that it is designed to convert a list
   * of results into a Map based on one of the properties in the resulting
   * objects.
   * @param <K> the returned Map keys type
   * @param <V> the returned Map values type
   * @param statement Unique identifier matching the statement to use.
   * @param parameter A parameter object to pass to the statement.
   * @param mapKey The property to use as key for each value in the list.
   * @return Map containing key pair data.
   */
  <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey);

  /**
   * The selectMap is a special case in that it is designed to convert a list
   * of results into a Map based on one of the properties in the resulting
   * objects.
   * @param <K> the returned Map keys type
   * @param <V> the returned Map values type
   * @param statement Unique identifier matching the statement to use.
   * @param parameter A parameter object to pass to the statement.
   * @param mapKey The property to use as key for each value in the list.
   * @param rowBounds  Bounds to limit object retrieval
   * @return Map containing key pair data.
   */
  <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowBounds);

  /**
   * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
   * @param <T> the returned cursor element type.
   * @param statement Unique identifier matching the statement to use.
   * @return Cursor of mapped objects
   */
  <T> Cursor<T> selectCursor(String statement);

  /**
   * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
   * @param <T> the returned cursor element type.
   * @param statement Unique identifier matching the statement to use.
   * @param parameter A parameter object to pass to the statement.
   * @return Cursor of mapped objects
   */
  <T> Cursor<T> selectCursor(String statement, Object parameter);

  /**
   * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
   * @param <T> the returned cursor element type.
   * @param statement Unique identifier matching the statement to use.
   * @param parameter A parameter object to pass to the statement.
   * @param rowBounds  Bounds to limit object retrieval
   * @return Cursor of mapped objects
   */
  <T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds);

  /**
   * Retrieve a single row mapped from the statement key and parameter
   * using a {@code ResultHandler}.
   * @param statement Unique identifier matching the statement to use.
   * @param parameter A parameter object to pass to the statement.
   * @param handler ResultHandler that will handle each retrieved row
   */
  void select(String statement, Object parameter, ResultHandler handler);

  /**
   * Retrieve a single row mapped from the statement
   * using a {@code ResultHandler}.
   * @param statement Unique identifier matching the statement to use.
   * @param handler ResultHandler that will handle each retrieved row
   */
  void select(String statement, ResultHandler handler);

  /**
   * Retrieve a single row mapped from the statement key and parameter
   * using a {@code ResultHandler} and {@code RowBounds}
   * @param statement Unique identifier matching the statement to use.
   * @param rowBounds RowBound instance to limit the query results
   * @param handler ResultHandler that will handle each retrieved row
   */
  void select(String statement, Object parameter, RowBounds rowBounds, ResultHandler handler);

 /**
  * 插入对象
  * @param statement
  * @return
  */
  int insert(String statement);

  /**
   * 带参数的插入对象
   * @param statement
   * @param parameter
   * @return
   */
  int insert(String statement, Object parameter);

  /**
   * 更新对象
   * @param statement
   * @return
   */
  int update(String statement);

  /**
   * 待参数的更新对象
   * @param statement
   * @param parameter
   * @return
   */
  int update(String statement, Object parameter);

  /**
   * 删除对象
   * @param statement
   * @return
   */
  int delete(String statement);

 /**
  * 待参数的删除对象
  * @param statement
  * @param parameter
  * @return
  */
  int delete(String statement, Object parameter);

  /**
   * 提交
   */
  void commit();

  /**
   * 是否强制提交
   * @param force
   */
  void commit(boolean force);

  /**
   * 回滚
   */
  void rollback();
  /**
 * 是否强制回滚
 * @param force
 */
  void rollback(boolean force);

  /**
   * 刷新执行,返回一个结果集的列表
   * @return
   */
  List<BatchResult> flushStatements();

  /**
   * 关闭session对象
   */
  @Override
  void close();

  /**
   * 清除缓存
   */
  void clearCache();

  /**
   * 获取配置对象
   * @return
   */
  Configuration getConfiguration();

  /**
   * 根据一个接口产生其Mapper的实现
   * @param type
   * @return
   */
  <T> T getMapper(Class<T> type);

  /**
   * 获取连接
   * @return
   */
  Connection getConnection();
}
